Summary of changes

This PR introduces a new framework for writing Ethernet MAC drivers. The existing EMAC interface requires MAC drivers to implement quite a lot of the specifics of memory management, MAC address tracking, and DMA themselves, even though quite a bit of this logic is common to all MAC drivers. This has led to duplicated code, and quite often to half-assed code as well as chip vendors have struggled to conform to the (admittedly not very well defined) EMAC API.

CompositeEMAC should make this a thing of the past. It's a class which implements the EMAC API and delegates its duties to four subclasses:

• A MAC peripheral driver
• A Tx DMA ring driver
• An Rx DMA ring driver
• A PHY driver

The first three of those classes are provided by the chip-specific EMAC driver, while the fourth comes from a library of PHY drivers and is not MCU specific. But this way most of the tough logic can be done in the non-MCU-specific layer, and all that needs to be done on a per-MCU basis is writing the low level MAC driver and low level code to interact with Ethernet descriptors.

See detailed documentation here: https://github.com/mbed-ce/mbed-os/blob/dev/stm32-emac-rewrite/connectivity/drivers/emac/CompositeEMAC.md

Impact of changes

• Ethernet support added for STM32H5
• Significant Ethernet speed improvement for STM32H7: MAC no longer blocks while packets are being sent
• Also, data cache no longer gets disabled when you use Ethernet on STM32H7. Apparently someone just made the driver globally disable the cache to fix a bug...
• Zero-copy Ethernet support for STM32 devices, so small packets can be received with less wasted memory and large packets can be received with no copying
• Generic PHY driver system allows any PHY supported by Mbed to be used with any MCU. Previously the PHY was hardcoded into the EMAC driver, so you had to use that exact model of PHY.

Migration actions required

If you have a custom target for an STM32 board with Ethernet support, you will need to update your stm32_eth_init.c. The following changes were made to these files in this PR:

• void HAL_ETH_MspInit(ETH_HandleTypeDef *heth) renamed to void EthInitPinmappings(void)
• void HAL_ETH_MspDeInit(ETH_HandleTypeDef *heth) renamed to void EthDeinitPinmappings()
• Any and all DCACHE disabling removed. The ethernet driver now fully supports the data cache!
• void stm32_eth_init_weak_symbol_helper() removed, no longer needed
• New function added: PinName EthGetPhyResetPin(void). This should return the GPIO pin connected to the phy reset line. If there is none, then it should return NC and a software reset will be used instead.

Here's an example of the changes: https://github.com/mbed-ce/mbed-os/pull/438/files#diff-7902496d820b51eb5e98851cbbe5cfcb5b2b68ef7af6d9a8e2650d2ada37ab4c

Documentation

Pull request type

[] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[] Feature update (New feature / Functionality change / New API)
[X] Major update (Breaking change E.g. Return code change / API behaviour change)

Test results

[] No Tests required for this change (E.g docs only update)
[] Covered by existing mbed-os tests (Greentea or Unittest)
[X] Tests / results supplied as part of this PR

Successfully ran EMAC and netsocket tests on STM32H563 and STM32F429ZI. Only failures are the nanostack ones (which are known broken at present).